home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / a86b.arc / EQU.DOC < prev    next >
Text File  |  1986-06-22  |  5KB  |  111 lines
  1. ---EQU.DOC---
  2.  
  3. The EQU Directive
  4.  
  5. Syntax: symbol-name EQU expression
  6.         symbol-name EQU built-in-symbol
  7.         symbol-name EQU INT n
  8.  
  9. The expression field may specify an operand of any type that could appear as an
  10. operand to an instruction.
  11.  
  12. As a simple example, suppose you are writing a program that manipulates a table
  13. containing 100 names and that you want to refer to the maximum number of names
  14. throughout the source file.  You can, of course, use the number 100 to refer to
  15. this maximum each time, as in MOV CX,100, but this approach suffers from two
  16. weaknesses.  First of all, 100 can mean a lot of things; in the absence of
  17. comments, it is not obvious that a particular use of 100 refers to the maximum
  18. number of names.  Secondly, if you extend the table to allow 200 names, you will
  19. have to locate each 100 and change it to a 200.  Suppose, instead, that you
  20. define a symbol to represent the maximum number of names with the following
  21. statement:
  22.  
  23. MAX_NAMES EQU 100
  24.  
  25. Now when you use the symbol MAX_NAMES instead of the number 100 (for example,
  26. MOV CX,MAX_NAMES), it will be obvious that you are referring to the maximum
  27. number of names in the table.  Also, if you decide to extend the table, you need
  28. only change the 100 in the EQU directive to a 200 and every reference to
  29. MAX_NAMES will reflect the change.
  30.  
  31. You could also take advantage of A86's strong-typing, by changing MAX_NAMES to
  32. a variable:
  33.  
  34. MAX_NAMES  DB ?
  35.  
  36. or even an indexed quantity:
  37.  
  38. MAX_NAMES EQU [BX+1]
  39.  
  40. Because the A86 language is strongly-typed, the instruction for loading
  41. MAX_NAMES into the CX-register remains exactly the same in all cases: simply
  42. MOV CX,MAX_NAMES.
  43.  
  44.  
  45. Equates to Built-In Symbols
  46.  
  47. A86 allows you to define synonyms for any of the assembler reserved-symbols,
  48. by EQUating an alternate name of your choosing, to that symbol.  For example,
  49. suppose you were coding a source module that is to be incorporated into
  50. several different programs.  In some programs, a certain variable will exist
  51. in the code segment.  In others, it will exist in the stack segment.  You want
  52. to address the variable in the common source module, but you don't know which
  53. segment-override to use.  The solution is to declare a synonym, QS, for the
  54. segment register.  QS will be defined by each program: the code-segment program
  55. will have a QS EQU CS at the top of it; the stack-segment program will have
  56. QS EQU SS.  The source module can use QS as an override, just as if it were
  57. CS or SS.  The code would be, for example, QS MOV AL,VARNAME.
  58.  
  59. The NIL Prefix
  60.  
  61. A86 provides a mnemonic, NIL, that generates no code.  NIL can be used as
  62. a prefix to another instruction (which will have no effect on that instruction),
  63. or it can appear by itself on a line.  NIL is provided to extend the example
  64. in the previous section, to cover the possibility of no-overrides.  If your
  65. source module goes into a program that fits into 64K, so that all the segment
  66. registers have the same value, then code QS EQU NIL at the top of that program.
  67.  
  68.  
  69. Interrupt Equates
  70.  
  71. A86 allows you to equate your own name to an INT-instruction with a specific
  72. interrupt-number.  For example, if you place  TRAP EQU INT 3  at the top of
  73. your program, you can use the name TRAP as a synonym for INT 3  (the debugger
  74. trap on the 8086).
  75.  
  76.  
  77. Duplicate Definitions
  78.  
  79. A86 contains the unique feature of duplicate definitions.   We have already
  80. discussed local symbols, which can be redefined to different values without
  81. restriction.  Local symbols are the only symbols that can be redefined.
  82. However, any symbol can be defined more than once, as long as the symbol is
  83. defined to be the same value and type in each definition.
  84.  
  85. This feature has two uses.  First, it eases modular program development.  For
  86. example, if two independently-developed source files both use the symbol ESC to
  87. stand for the ASCII code for ESCAPE, they can both contain the declaration ESC
  88. EQU 01B, with no problems if they are combined into the same program.
  89.  
  90. The second use for this feature is assertion-checking.  Your delibarate
  91. re-declaration of a symbol name is an assertion that the value of the symbol has
  92. not changed; and you want the assembler to issue you an error message if it has
  93. changed.  Example: suppose you have declared a table of options in your DATA
  94. segment; and you have another table of initial values for those options in your
  95. CODE segment.  If you come back months later and add an option to your tables,
  96. you want to be reminded to update both tables in the same way.  You should
  97. declare your tables as follows:
  98.  
  99. DATA SEGMENT
  100.   OPTIONS:
  101.     .
  102.     .
  103.   OPT_COUNT EQU $-OPTIONS    ; OPT_COUNT is the size of the table
  104.  
  105. CODE SEGMENT
  106.   OPT_INITS:
  107.     .
  108.     .
  109.   OPT_COUNT EQU $-OPT_INITS  ; second OPT_COUNT had better be the same!
  110.  
  111.